How to Make Display Files
-------------------------


Introduction
-------------
Display files are based on the original artwork files used in mame. In case you weren't aware,
mame has the ability to turn various portions of the artwork on and off depending upon a output state 
change.  Display files allow you to take this concept out of mame and display the mame-controlled artwork
else-where.  The most logical reason to do this is if you have a dual screen cabinet and you want to display 
secondary info on the secondary screen.  There are probably other uses but I am not aware of them.



Building a Display File - Getting Started
-----------------------------------------
Each display file and it's images are stored in a folder, that should be named what you want to call the display.
The display file you create inside should be named the same as the folder.  To call a display in mamehooker, you use
the command:

lds display_name

Where "display_name" is the name of the folder.  The images should also be put in this folder.  Supported image formats
are jpg, gif and bmp.  Sorry, but I won't add png support because unlike in mame, blending effects aren't required
as the layouts are "solid" (no empty area to place the game) and gif files add limited transparency support if needed.

If you ever get confused while reading through this document, the best thing to do is look at the "test" folder in the
displays folder of mamehooker.  It has a fully working example you can look at.  Inside is a readme telling you how to setup
mamehooker so that the test display is loaded for every game and displays the status of the start/coin lights if the game
supports those outputs.  A good one to try is digdug.


Builing a Display File - Layout options
---------------------------------------
The layout defines basic attributes about the entire artwork surface, including position, size and the 
background image.  The layout is basically the background surface to which all other controllable elements
are applied.  The layout section of your dis file should look like this:


[Layout]
x=
y=
height=
width=
NumberofImages=2
image=background.jpg

The order of the entires is not important, but don't add any extra space between the value and the "=" sign.

Note the x,y,width and height values are blank.... since you'll generally be using the same layout dimensions for
each display you can leave these blank in individual files and define them in the default.dis, which you've probably
noticed already.

X and Y determine the position of the top, left-hand corner of the layout surface.  These values are in pixels.
To put the display on a secondary monitor, you simply use values greater, or less than the resolution of the 
primary monitor.  Confused?  Well let's say that your extra monitor is above and on the left edge of your primary
monitor (in windows desktop managment, NOT in real life).  Let's also assume that it runs at 640x480.  Well to make a
layout display on it, we set the y to -480, which is 480 pixels above 0 (the top of your primary monitor) which will make 
it align with the top of your extra monitor.  They are both on the same edge, so the x value is 0, like it would be on the 
primary monitor.  Let's say the extra monitor is below the primary one, well you take the resolution the primary monitor is 
running at, lets say 1024x768 and you add 1 to the height.  So a y value of 769 will make it align with the top of your 
extra screen. 

Height and width are what you would expect, in pixels of course.  Something of note is that if you have more than two screens,
you can use these to make the layout file span multiple monitors..... just make the width or height double what it would be 
normally.  

Number of Images tells the display how many controllable image elements to look for.  If this number is lower than the number
of elements you've made, the last few elements won't work.  You should set this after you are done building your display so you
can count the elements.

The image entry will be the background image for the layout area.  I suggest that you use ony jpgs for this as gifs are palletted,
causing larger ones to flicker when they are refreshed and bmps are huge.



Building a Display File - Image elements
----------------------------------------
Now that we have a layout defined it's time to put some things on it we can control.  Basically display files contain groups of 
images that are swapped out depening upon the number passed, we call these groups image elements.  You can have as many elements
as you want, but remember that you need to define the number of elements in your "numberofimages" entry in the layout section.
Also note that the header for image cfgs must be in the syntax "[Image#]" where number is the number of the element.  You cannot
skip around, so if you have 5 elements then their numbers must be 1, 2, 3, 4 and 5 not any random old numbers you choose.  This is
done so strictly so that the display file can be parsed quicker. Mame takes a while to setup the artwork, but mamehooker doesn't. ;-)

Each element has a setup something like this:

[Image1]
x=.1
y=.1
height=.80
width=.30
length=2
image=Counter_01_#.jpg

Note the header, this is our first element.  To control it in mame hooker we use the command:
 
sds 1 # 

Where # is the image number you wish to set this element to.  

X, y, height and width are just like in the layout section, but in precentage of the layout area.  1 is = 100% .5 is 50% .01 is 1% ect...
If you have trouble figuring out the percents, there is an info tool in photoshop that'll help.  In it's options set the position measurment
value to % and now when you move your cursor around an image, the positon will show up in percent.  You can load up your background image and determine
position and size that way.

The length entry refers to how many different images we want to be able to swap out.  In this case, the image is only off or on, so we have 2 images to deal 
with.

The "image" entry actually refers to all of your images, not just one.  Note the "#" in the filename, this part of the name is unique for each image in the 
element.  Also be aware that the first image in an element is always 0, not 1.  So in our example we would make a "Counter_01_0.jpg" and a "Counter_01_1.jpg"
to switch between them we use the sds command with the # being either 0 or 1.  One thing to note is that if you do not make an image for a state number 
nothing will be displayed when the element is set to that number.  This is a good thing as we don't have to make unnecessary images.  As a matter of fact,
if you look at mame's artwork files they also work this way.  Generally speaking you want the off (0) state to be part of the background image for the layout
this way we save file size and resources when the display is loaded.  Most piece of artwork only have on and off (1 and 0) but things like segmented digits 
can have many.  


Building a Display File - Hooking it up
---------------------------------------
Now we are finished building the display file, but to have it setting in the displays folder is not enough, your need to write a script to hook it up
to outputs.  Generally speaking you use a different display file for each game, so let's asumme you made a display file for seawolf.  You firstly need to
make an ini file for it in the ini folder called seawolf.ini.  It should look like this:

[General]
MameStart=lds seawolf
MameStop=
StateChange=
[Output]
ready_lamp=sds 1 %s%
RELOAD_LAMP=sds 2 %s%

TORP_LAMP_1=sds 3 %s%
TORP_LAMP_2=sds 4 %s%
TORP_LAMP_3=sds 5 %s%
TORP_LAMP_4=sds 6 %s%

Note the mamestart entry, it loads a display file called seawolf whenver the seawolf game is played in mame.  The display file automatically closes when you
exit mame. Also note all the output entries, they are linking the various seawolf outputs to image element 1 - 6 in the display file.  How did I figure these
out?  Well the easiest way is to download the official artwork file for mame and look at the layout file.  The names the mame elements are linked to are the
output names.  If a mame file doesn't exist, playing the game while mamehooker is active will print the outputs to the ini file.  Once you have all of this 
hooked up, your display file will automatically load and work for that game.  Note that you can use the same display for multiple games, you only need to 
copy the ini file and rename it for each game you wish to use it for. 


Packaging a Display File
-------------------------

If you wish to distribute your display file, you'll want to package everything up in a zip.  Make a temp folder somewhere on your drive.  In the temp folder
create the folders  "displays" and "ini"  Take the ini file you made for the display and put it in the ini folder.  Take the folder you put your display
stuff in and put it in the display folder.  If you wish to include a readme, put it inside the folder for your display. Select both folders inside your temp
folder and add them to a zip.  Name the zip after the display.  When people install the display, they should place the zip in the root of the mamehooker
folder and "extract here".  

Just to make things clear, using our seawolf example, we would have a temp folder. Inside the folder are the folders "ini" and "displays". Inside the "ini"
folder is the seawolf.ini.  Inside the "displays" folder is another folder called "seawolf" and in that folder we have are .dis file, all it's images and an
optional readme file.  Got it?